<html>
<head><meta charset="utf-8"><title>Iterator docs · t-libs · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/index.html">t-libs</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html">Iterator docs</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="223638444"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223638444" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Ashley Mannix <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223638444">(Jan 22 2021 at 13:08)</a>:</h4>
<p>Hey! I've been thinking about our <code>Iterator</code> docs lately and thought it might be nice to give them a bit of TLC. Before going through the large number of methods though I thought I'd test the waters with <code>fold()</code>. I thought it would be good if all of our <code>Iterator</code> methods:</p>
<ul>
<li>Had a basic example, preferably using a collection rather than successive calls to <code>assert_eq!(Some(expr), iter.next())</code></li>
<li>Had an example with at least one other adapter in it</li>
<li>Had a copy of the basic example implemented without iterators</li>
<li>Had a list of related methods</li>
</ul>
<p>This is where I got with <code>fold()</code>: <a href="https://hackmd.io/LX7MYKX_SCadkmLuRl4Wmg">https://hackmd.io/LX7MYKX_SCadkmLuRl4Wmg</a></p>
<p>What do you think? Do those seem like reasonable things to aim for? If so I'd like to go through a bunch of the other adapters.</p>



<a name="223638665"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223638665" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Ashley Mannix <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223638665">(Jan 22 2021 at 13:10)</a>:</h4>
<p>Some specific changes to <code>fold()</code> include moving _Notes to Implementors_ to the bottom and replacing the table with the output of <code>dbg!</code> (I never found the table very helpful because it renders very wide so I found it hard to digest)</p>



<a name="223639286"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223639286" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> simulacrum <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223639286">(Jan 22 2021 at 13:16)</a>:</h4>
<p>I do worry a bit that it'll make the iterator page even longer, but scrolling through it is already unreasonable so seems okay.</p>



<a name="223639395"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223639395" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Ashley Mannix <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223639395">(Jan 22 2021 at 13:17)</a>:</h4>
<p>Yeh it’s quite unwieldy. That’s what got me thinking about the “Related Methods” section to maybe give us some more semantic navigation</p>



<a name="223639579"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223639579" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Ashley Mannix <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223639579">(Jan 22 2021 at 13:19)</a>:</h4>
<p>We could also be a little more tactical. I can imagine methods like <code>max</code> or <code>sum</code> are clear enough to not need a lot of content</p>



<a name="223643719"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223643719" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> simulacrum <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223643719">(Jan 22 2021 at 13:56)</a>:</h4>
<p>I do wonder - another strategy could be brief summaries on the method, and longer summaries on the return type, which for most of the interesting adapters would be unique</p>



<a name="223644027"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223644027" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Ashley Mannix <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223644027">(Jan 22 2021 at 13:59)</a>:</h4>
<p>That would work for something like <code>scan</code> <span aria-label="thinking" class="emoji emoji-1f914" role="img" title="thinking">:thinking:</span> But wouldn’t really for <code>fold</code></p>



<a name="223644446"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223644446" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> simulacrum <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223644446">(Jan 22 2021 at 14:02)</a>:</h4>
<p>Yeah, true.</p>



<a name="223647012"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223647012" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223647012">(Jan 22 2021 at 14:23)</a>:</h4>
<p>If rustdoc can help here, I'm happy for suggestions :)</p>



<a name="223702515"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223702515" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Josh Triplett <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223702515">(Jan 22 2021 at 21:25)</a>:</h4>
<p><span class="user-mention silent" data-user-id="204346">Ashley Mannix</span> <a href="#narrow/stream/219381-t-libs/topic/Iterator.20docs/near/223638444">said</a>:</p>
<blockquote>
<p>Hey! I've been thinking about our <code>Iterator</code> docs lately and thought it might be nice to give them a bit of TLC. Before going through the large number of methods though I thought I'd test the waters with <code>fold()</code>. I thought it would be good if all of our <code>Iterator</code> methods:</p>
<ul>
<li>Had a basic example, preferably using a collection rather than successive calls to <code>assert_eq!(Some(expr), iter.next())</code></li>
<li>Had an example with at least one other adapter in it</li>
<li>Had a copy of the basic example implemented without iterators</li>
<li>Had a list of related methods</li>
</ul>
<p>This is where I got with <code>fold()</code>: <a href="https://hackmd.io/LX7MYKX_SCadkmLuRl4Wmg">https://hackmd.io/LX7MYKX_SCadkmLuRl4Wmg</a></p>
<p>What do you think? Do those seem like reasonable things to aim for? If so I'd like to go through a bunch of the other adapters.</p>
</blockquote>
<p>FWIW, I would love to see most examples using collections rather than <code>.next()</code> calls, but at the same time, I'd also love to see a few examples at the top showing the equivalence, using <code>assert_eq!(..., iter.next())</code>. That helped greatly when learning iterators.</p>



<a name="223702579"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223702579" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Josh Triplett <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223702579">(Jan 22 2021 at 21:25)</a>:</h4>
<p>We don't need to re-demonstrate that in every iterator method. But it'd be nice to have a couple of examples in the <code>iter.next()</code> style attached to <code>Iterator</code> itself.</p>



<a name="223725737"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/219381-t-libs/topic/Iterator%20docs/near/223725737" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Lokathor <a href="https://rust-lang.github.io/zulip_archive/stream/219381-t-libs/topic/Iterator.20docs.html#223725737">(Jan 23 2021 at 02:06)</a>:</h4>
<p>Personally I find the .next usage to be the clearest way to do an example with iterators, but maybe that's just me</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>